<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Db::set_bt_compress()</title>
    <link rel="stylesheet" href="apiReference.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB C++ API Reference" />
    <link rel="up" href="db.html" title="Chapter 2.  The Db Handle" />
    <link rel="prev" href="dbset_bt_compare.html" title="Db::set_bt_compare()" />
    <link rel="next" href="dbset_bt_minkey.html" title="Db::set_bt_minkey()" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Db::set_bt_compress()</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="dbset_bt_compare.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 2. 
                The Db Handle
        </th>
          <td width="20%" align="right"> <a accesskey="n" href="dbset_bt_minkey.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="dbset_bt_compress"></a>Db::set_bt_compress()</h2>
          </div>
        </div>
      </div>
      <pre class="programlisting">#include &lt;db_cxx.h&gt;

extern "C" {
    typedef int (*bt_compress_fcn_type)(DB *db, const DBT *prevKey, 
        const DBT *prevData, const DBT *key, const DBT *data, DBT *dest);
    typedef int (*bt_decompress_fcn_typ)(DB *db, const DBT *prevKey, 
        const DBT *prevData, DBT *compressed, DBT *destKey, 
        DBT *destData);
};
int
Db::set_bt_compress(bt_compress_fcn_type bt_compress_fcn, 
    bt_decompress_fcn_type bt_decompress_fcn);</pre>
      <p>
        Set the Btree compression and decompression functions.  The
        compression function is called whenever a key/data pair is added to
        the tree and the decompression function is called whenever data is
        requested from the tree.
   </p>
      <p>
       This method is only compatible with prefix-based compression
       routines. This callback is mostly intended for compressing keys.
       From a performance perspective, it is better to perform compression
       of the data portion of your records outside of the Berkeley DB
       library.
    </p>
      <p>
        If NULL function pointers are specified, then default compression
        and decompression functions are used.  Berkeley DB's default
        compression function performs prefix compression on all keys and
        prefix compression on data values for duplicate keys.  If using
        default compression, both the default compression and decompression
        functions must be used.
   </p>
      <p>
        The <code class="methodname">Db::set_bt_compress()</code> method
        configures operations performed using the specified <a class="link" href="db.html" title="Chapter 2.  The Db Handle">Db</a>  handle, not all operations
        performed on the underlying database.
   </p>
      <p>
        The <code class="methodname">Db::set_bt_compress()</code> method may not be called after the 
        <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a>  method is called. If
        the database already exists when <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a>  
        is called, the information specified to <code class="methodname">Db::set_bt_compress()</code> must be the same as
        that historically used to create the database or corruption can occur.
   </p>
      <p>
        The <code class="methodname">Db::set_bt_compress()</code> <span>
            
            <span>
                method either returns a non-zero error value or throws an
                exception that encapsulates a non-zero error value on
                failure, and returns 0 on success.
            </span>
        </span>
   </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp1674664"></a>Parameters</h3>
            </div>
          </div>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp1469760"></a>bt_compress_fcn</h4>
              </div>
            </div>
          </div>
          <p>
                         The <span class="bold"><strong>bt_compress_fcn</strong></span> function is the
                         application-specified Btree compression function.  The compression
                         function takes six parameters:
                    </p>
          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p>
                               <code class="literal">db</code>
                           </p>
                <p>
                                The <span class="bold"><strong>db</strong></span> parameter is the enclosing
                                database handle.
                           </p>
              </li>
              <li>
                <p>
                               <code class="literal">prevKey</code>
                            </p>
                <p>
                                The <span class="bold"><strong>prevKey</strong></span>
                                parameter is the <a class="link" href="dbt.html" title="Chapter 4.  The Dbt Handle">Dbt</a>
                                representing the key immediately preceding
                                the application supplied key.
                           </p>
              </li>
              <li>
                <p>
                               <code class="literal">prevData</code>
                            </p>
                <p>
                                The <span class="bold"><strong>prevData</strong></span>
                                parameter is the <a class="link" href="dbt.html" title="Chapter 4.  The Dbt Handle">Dbt</a>
                                representing the data associated with
                                <span class="bold"><strong>prevKey</strong></span>.
                           </p>
              </li>
              <li>
                <p>
                               <code class="literal">key</code>
                           </p>
                <p>
                                The <span class="bold"><strong>key</strong></span>
                                parameter is the 
                                <a class="link" href="dbt.html" title="Chapter 4.  The Dbt Handle">Dbt</a>
                                representing the application supplied key.
                           </p>
              </li>
              <li>
                <p>
                               <code class="literal">data</code>
                           </p>
                <p>
                                The <span class="bold"><strong>data</strong></span> parameter is the 
                                <a class="link" href="dbt.html" title="Chapter 4.  The Dbt Handle">Dbt</a>  representing the application
                                supplied data.
                           </p>
              </li>
              <li>
                <p>
                               <code class="literal">dest</code>
                           </p>
                <p>
                                The <span class="bold"><strong>dest</strong></span>
                                parameter is the 
                                <a class="link" href="dbt.html" title="Chapter 4.  The Dbt Handle">Dbt</a>
                                representing the data stored in the tree,
                                where the function should write the
                                compressed data.
                           </p>
              </li>
            </ul>
          </div>
          <p>
                   The <span class="bold"><strong>bt_compress_fcn</strong></span>
                   function must return 0 on success and a non-zero value
                   on failure.  If the compressed data cannot fit in
                    
                   <span class="bold"><strong>dest-&gt;set_data()</strong></span> 
                   (the size of which is
                   
                   <span>
                        returned by
                        <span class="bold"><strong>dest-&gt;get_ulen()</strong></span>),
                    </span>
                   the function should identify the required buffer size in 
                    
                   <span class="bold"><strong>dest-&gt;set_size()</strong></span> 
                   and return <code class="literal">DB_BUFFER_SMALL</code>.
           </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp72464"></a>bt_decompress_fcn</h4>
              </div>
            </div>
          </div>
          <p>
                         The <span class="bold"><strong>bt_decompress_fcn</strong></span> function is the
                         application-specified Btree decompression function.  The decompression
                         function takes six parameters:
                    </p>
          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p>
                               <code class="literal">db</code>
                           </p>
                <p>
                                The <span class="bold"><strong>db</strong></span> parameter is the enclosing
                                database handle.
                           </p>
              </li>
              <li>
                <p>
                               <code class="literal">prevKey</code>
                            </p>
                <p>
                                The <span class="bold"><strong>prevKey</strong></span>
                                parameter is the 
                                <a class="link" href="dbt.html" title="Chapter 4.  The Dbt Handle">Dbt</a>
                                representing the key immediately preceding
                                the key being decompressed.
                           </p>
              </li>
              <li>
                <p>
                               <code class="literal">prevData</code>
                            </p>
                <p>
                                The <span class="bold"><strong>prevData</strong></span>
                                parameter is the 
                                <a class="link" href="dbt.html" title="Chapter 4.  The Dbt Handle">Dbt</a>
                                representing the data associated with
                                <span class="bold"><strong>prevKey</strong></span>.
                           </p>
              </li>
              <li>
                <p>
                               <code class="literal">compressed</code>
                           </p>
                <p>
                                The 
                                <span class="bold"><strong>compressed</strong></span>
                                parameter is the 
                                <a class="link" href="dbt.html" title="Chapter 4.  The Dbt Handle">Dbt</a>
                                representing the data stored in the tree,
                                that is, the compressed data.
                           </p>
              </li>
              <li>
                <p>
                               <code class="literal">destKey</code>
                           </p>
                <p>
                                The <span class="bold"><strong>key</strong></span>
                                parameter is the <a class="link" href="dbt.html" title="Chapter 4.  The Dbt Handle">Dbt</a> where
                                the decompression function should store the
                                decompressed key.
                           </p>
              </li>
              <li>
                <p>
                               <code class="literal">destData</code>
                           </p>
                <p>
                                The <span class="bold"><strong>data</strong></span>
                                parameter is the
                                <a class="link" href="dbt.html" title="Chapter 4.  The Dbt Handle">Dbt</a> where
                                the decompression function should store the
                                decompressed key.
                           </p>
              </li>
            </ul>
          </div>
          <p>
                   The <span class="bold"><strong>bt_decompress_fcn</strong></span>
                   function must return 0 on success and a non-zero value
                   on failure.
                   If the decompressed data cannot fit in
                    
                   <span class="bold"><strong>key-&gt;set_data()</strong></span> 
                   or
                    
                   <span class="bold"><strong>data-&gt;set_data()</strong></span> 
                   (the size of which is
                   
                   <span>
                       returned by the <a class="link" href="dbt.html" title="Chapter 4.  The Dbt Handle">Dbt</a>'s
                        <span class="bold"><strong>get_ulen()</strong></span> method),
                    </span>
                   the function should identify the required buffer size 
                   
                   <span>
                       using the <a class="link" href="dbt.html" title="Chapter 4.  The Dbt Handle">Dbt</a>'s
                        <span class="bold"><strong>set_size()</strong></span> 
                        method
                    </span>
                   and return <code class="literal">DB_BUFFER_SMALL</code>.
           </p>
        </div>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp532272"></a>Errors</h3>
            </div>
          </div>
        </div>
        <p>
                        The <code class="methodname">Db::set_bt_compress()</code> <span>
            
            <span>
                method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 
                exception, encapsulating one of the following non-zero errors, or return one
                of the following non-zero errors:
            </span>
        </span>
                   </p>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp1422712"></a>EINVAL</h4>
              </div>
            </div>
          </div>
          <p>
                If the method was called after <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> 
                was called; or if an invalid flag value or parameter was specified.
            </p>
        </div>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp2902000"></a>Class</h3>
            </div>
          </div>
        </div>
        <p>
               <a class="link" href="db.html" title="Chapter 2.  The Db Handle">Db</a>  
           </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp967192"></a>See Also</h3>
            </div>
          </div>
        </div>
        <p>
                    <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 
               </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="dbset_bt_compare.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="db.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="dbset_bt_minkey.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Db::set_bt_compare() </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Db::set_bt_minkey()</td>
        </tr>
      </table>
    </div>
  </body>
</html>
